Requisições de Contestação

Esta página irá guiá-lo através dos endpoints para gerenciar contestações de transações Pix. Uma contestação é um processo formal onde o cliente questiona uma transação Pix, alegando que ela foi realizada de forma fraudulenta, por erro operacional ou sem sua autorização. Através destes endpoints, você pode criar, consultar, listar e cancelar solicitações de contestação.

Criar solicitação de contestação

Este endpoint é usado para criar uma nova solicitação de contestação para uma transação Pix.

Request

URL
cURL

POST https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes

Exemplo para OPERATIONAL_FAILURE:

curl -X POST https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes \
  -H "Content-Type: application/json" \
  -H "x-delbank-api-key: ••••••" \
  -H "x-delfinance-account-id	: ••••••" \
  -d '{
    "endToEndId": "E12345678202412101234567890123456",
    "disputeType": "OPERATIONAL_FAILURE",
    "details": "´Exemplo de detalhes"
  }'

Exemplo para SUSPECTED_FRAUD (com SituationType):

curl -X POST https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes \
  -H "Content-Type: application/json" \
  -H "x-delbank-api-key: ••••••" \
  -H "account: ••••••" \
  -d '{
    "endToEndId": "E12345678202412101234567890123456",
    "disputeType": "SUSPECTED_FRAUD",
    "details": "´Exemplo de detalhes",
    "SituationType": "COERCION"
  }'

Headers

Name	Description
Content-Type	Obrigatório. application/json
x-delbank-api-key	Obrigatório. Chave da API para autenticação
x-delfinance-account-id	Obrigatório. Identificador da conta

Parâmetros do Body

Parâmetro	Tipo	Descrição
endToEndId	`string`	Obrigatório. Identificador fim-a-fim da transação Pix
disputeType	`enum`	Obrigatório. Tipo de contestação. Domínios: `OPERATIONAL_FAILURE` - Falha operacional, `SUSPECTED_FRAUD` - Suspeita de fraude
details	`string`	Obrigatório. Detalhes sobre a contestação (máximo 2.000 caracteres)
situationType	`enum`	Opcional. Obrigatório apenas quando disputeType for `SUSPECTED_FRAUD`. Domínios: `SCAM` - Golpe, `ACCOUNT_TAKEOVER` - Conta tomada por terceiros, `COERCION` - Coerção, `FRAUDULENT_ACCESS` - Acesso fraudulento, `OTHER` - Outros

Regras Importantes:

Ao usar disputeType: "OPERATIONAL_FAILURE", NÃO inclua o campo SituationType
Ao usar disputeType: "SUSPECTED_FRAUD", o campo SituationType é obrigatório

Body

Exemplo para OPERATIONAL_FAILURE

{
  "endToEndId": "E12345678202412101234567890123456",
  "disputeType": "OPERATIONAL_FAILURE",
  "details": "´Exemplo de detalhes"
}

Exemplo para SUSPECTED_FRAUD:

{
  "endToEndId": "E12345678202412101234567890123456",
  "disputeType": "SUSPECTED_FRAUD",
  "details": "´Exemplo de detalhes",
  "SituationType": "COERCION"
}

Resposta

O código de status 201 indica sucesso na criação da contestação.

Se a solicitação for bem-sucedida, o retorno terá os seguintes campos em formato JSON:

{
  "id": "J3OKE0EBX8GKKUZC",
  "endToEndId": "E38224857202509251518IQT5PJKA64D",
  "disputeType": "OPERATIONAL_FAILURE",
  "transactionAmount": 8.00,
  "counterpartyName": "JOTINHA AFONSO",
  "status": "PENDING",
  "details": "Exemplo",
  "createdAt": "2025-10-01T16:54:45.865201657",
  "updatedAt": "2025-10-01T16:54:45.86520653",
  "deadlineAt": "2025-10-08T16:54:45.865207206"
}

Cancelar contestação

Este endpoint permite cancelar uma contestação existente.

Request

URL
cURL

PATCH https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes/:disputeId/cancel

curl --request PATCH \
  --url 'https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes/DSP123456789/cancel' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-delbank-api-key: YOUR_API_KEY' \
  --header 'x-delfinance-account-id: YOUR_ACCOUNT_ID' \
  --data '{
    "reason": "Cliente desistiu da contestação"
  }'

Headers

Name	Description
Content-Type	Obrigatório. application/json
x-delbank-api-key	Obrigatório. Chave da API para autenticação
x-delfinance-account-id	Obrigatório. Identificador da conta

Path Parameters:

Name	Type	Description
disputeId	`string`	Obrigatório. Identificador da contestação

Body

{
  "reason": "Cliente desistiu da contestação"
}

Resposta

O código de status 200 indica sucesso no cancelamento.

Se a solicitação for bem-sucedida, o retorno terá os seguintes campos em formato JSON:

{
  "id": "LUPRY7ZN08XF6673",
  "customerRole": "CLAIMANT",
  "accountNumber": "10138",
  "endToEndId": "E3822485720250929125712cQXATZ4n9",
  "disputeType": "SUSPECTED_FRAUD",
  "transactionAmount": 10.00,
  "counterpartyName": "TESTE PESSOAL",
  "status": "CANCELED",
  "details": "Detalhes da criação",
  "infractionNotificationId": null,
  "refundRequestId": null,
  "refundedAmount": null,
  "createdAt": "2025-10-01T13:02:23.996737",
  "updatedAt": "2025-10-02T17:30:05.117778758",
  "deadlineAt": "2025-10-08T13:02:23.996746",
  "analyzedAt": null,
  "analyzedBy": null,
  "analysisNotes": "CANCELADA PELO CLIENTE. Exemplo"
}

Obter contestação específica

Use este endpoint para obter informações sobre uma contestação específica.

Request

URL
cURL

GET https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes/:disputeId

curl --request GET \
  --url 'https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes/DSP123456789' \
  --header 'accept: application/json' \
  --header 'x-delbank-api-key: YOUR_API_KEY' \
  --header 'account: YOUR_ACCOUNT_ID'

Headers

Name	Description
x-delbank-api-key	Obrigatório. API key
x-delfinance-account-id	Obrigatório. O número da conta Delfinance.

Path Parameters:

Name	Type	Description
disputeId	`string`	Obrigatório. Identificador da contestação

Resposta

O código de status 200 indica sucesso na consulta.

Se a consulta for bem-sucedida, o retorno terá os seguintes campos em formato JSON:

{
  "disputeId": "DSP123456789",
  "endToEndId": "E38224857202501011234567890123456",
  "disputeType": "SUSPECTED_FRAUD",
  "details": "Transação não reconhecida pelo cliente",
  "situationType": "ACCOUNT_TAKEOVER",
  "status": "PENDING",
  "customerRole": "CLAIMANT",
  "createdAt": "2025-01-01T10:30:00.000Z",
  "updatedAt": "2025-01-01T10:30:00.000Z",
  "deadlineAt": "2025-01-15T23:59:59.999Z"
}

Listar contestações

Este endpoint permite buscar todas as contestações com filtros opcionais.

Request

URL
cURL

GET https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes

curl --request GET \
  --url 'https://apisandbox.delbank.com.br/baas/api/v1/pix/med/disputes?page=1&size=50' \
  --header 'accept: application/json' \
  --header 'x-delbank-api-key: YOUR_API_KEY' \
  --header 'account: YOUR_ACCOUNT_ID'

Headers

Name	Description
x-delbank-api-key	Obrigatório. API key
x-delfinance-account-id	Obrigatório. O número da conta Delfinance

Query Parameters:

Name	Type	Description
page	`number`	Número da página (padrão: 1)
size	`number`	Tamanho da página (padrão: 50)
disputeType	`enum`	Tipo de contestação. Domínios: `OPERATIONAL_FAILURE` - Falha operacional, `SUSPECTED_FRAUD` - Suspeita de fraude
status	`enum`	Status da contestação para filtrar. Domínios: `PENDING` - Pendente, `CANCELED` - Cancelada, `AWAITING_EVIDENCE` - Aguardando evidências, `ACCEPTED` - Aceita, `REJECTED` - Rejeitada
customerRole	`enum`	Papel do cliente (`CLAIMANT`)
deadlineAt	`date`	Data limite para filtrar
createdAt	`date`	Data de criação para filtrar

Resposta

O código de status 200 indica sucesso na consulta.

Se a consulta for bem-sucedida, o retorno terá os seguintes campos em formato JSON:

 [
    {
      "disputeId": "DSP123456789",
      "endToEndId": "E38224857202501011234567890123456",
      "disputeType": "SUSPECTED_FRAUD",
      "status": "PENDING",
      "customerRole": "CLAIMANT",
      "createdAt": "2025-01-01T10:30:00.000Z",
      "deadlineAt": "2025-01-15T23:59:59.999Z"
    },
    {
      "disputeId": "DSP987654321",
      "endToEndId": "E38224857202501019876543210987654",
      "disputeType": "OPERATIONAL_FAILURE",
      "status": "AWAITING_EVIDENCE",
      "customerRole": "CLAIMANT",
      "createdAt": "2024-12-28T15:45:00.000Z",
      "deadlineAt": "2025-01-12T23:59:59.999Z"
    }
  ]

Criar solicitação de contestação​

Request​

Headers​

Parâmetros do Body​

Body​

Resposta​

Cancelar contestação​

Request​

Headers​

Path Parameters:​

Body​

Resposta​

Obter contestação específica​

Request​

Headers​

Path Parameters:​

Resposta​

Listar contestações​

Request​

Headers​

Query Parameters:​

Resposta​

Criar solicitação de contestação

Request

Headers

Parâmetros do Body

Body

Resposta

Cancelar contestação

Request

Headers

Path Parameters:

Body

Resposta

Obter contestação específica

Request

Headers

Path Parameters:

Resposta

Listar contestações

Request

Headers

Query Parameters:

Resposta